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Abstract 
Over the past 10 years, the High Performance Software Designed Radio project has moved from the 
early attempt of producing an audio interface and a USB interface to a sophisticated single board single 
FPGA (Field Programmable Gate Array). In this process, the communication protocol and the software 
tools to manage that process have changed several times. Some of the reason things are organized in 
certain ways are an artifact of the history of the changes. This paper will chronical these changes and 
some of the resulting software that allow the loading and replacement of the firmware in the radio 
boards. 


Introduction 


This paper presents the design rational and motivation behind the firmware programming tools used by 
the openHPSDR Development Group (openhpsdr.org). To understand the need for the programming 
tools, you need to Know some history of the project. 


| started to participate in the HPSDR group in 2007. At that time the group had already developed the 
Atlas, which is a passive backplane board, Ozymandias an FPGA based interface controller card that 
provides the input and output connections to the real world, and J anus a dual, full duplex, A/D and D/A 
converter board, which is a board that could be used as a sound card interface to the FlexRadio 
SDR1000. Atthis pointin the project, custom firmware programming tools were not need as the only 
board with an FPGA (Field Programmable Gate A rray) was the Ozymandias board (Altera Cyclone II 
FPGA), which would read and reload its firmware on every startup from a file on the client computer. 


In 2008 at the DCC in Chicago, Scotty, WA2DFI asked me to manage the HPSDR web site. Dale, 
AE5K had started the web site in 2006 and had done a nice job setting up the structure. Since our group 
is not formally organized other than, we are interested in the development of Software Designed Radio 
(SDR) for the A mateur Radio community. | decided to maintain most of the original structure and keep 
it as a documentation of the development of the projects that the group worked on over the years. M any 
Hams find this makes the site confusing, as they are use to an organization that is trying to sell them a 
new product, older parts disappear from the site. This site endeavors to keep all the ideas posted and 
even the dead-end ones remain as someone might go and pick up one of these ideas again for further 
development. In addition, we have a Wiki system that was maintained, not by me, but the original 
author and many people started to develop interesting projects but then lose interest in the continued 
development before the project completion. My preference is to document past history of the project 
developments. 
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In 2007-2008 the group focused on a transmit board called Penelope, which is a digital up converter 
(DUC) a1/2-watt transmitter/exciter board. The developers were all in a learning curve and most of us 
were at different points in a learning curve. At this point, FPGAs were very reasonably priced and 
added tremendous flexibility to the development process. The Penelope used an A Itera Cyclone II like 
the Ozymandias board. This started the need to develop firmware for the individual component board 
that was not directly connected to a computer interface. Weused the Altera software to create and load 
the firmware into the component boards directly to pin connections on each individual component 
board. 


Then from 2008-2010 we developed the M ercury board, a 0-65M Hz Direct Sampling Receiver with a 
Altera Cyclone Ill FPGA. This board started the slow progression of changing hardware in the FPGA 
components. Wewould use the Altera software with a USB Blaster connected to a pin connector on 
the component board. The boards generally need a change of jumper pins to accept the firmware and a 
different pin setting to run the board. While the developer group was quite adept at programming 
boards, for the occasional user it was a daunting task. | have met many openH PSDR board owners that 
have not changed the original firmware shipped in the boards. 


So now we had a working transceiver and we found out the the boards were much more capable than we 
expected and the USB2 technology was one of the limiting factors. At this point, USB3 had been 
invented but was years from being widely available. Additionally, the USB technology had several 
quirks and the driver coding was quite complicated to write from the open source point of view. 


At this point in time, Ethernet 10/100 baseT technology was in most computers and 1000 base T was 
available. It was a stable and well-known technology. The 100k bandwidth could provide comparable 
bandwidth to the USB2 we were using. This led to the development of the M etis board, which provides 
either a 100 baseT or Gigabit (1000 baseT) interface to the host PC. It was designed so that the boards 
and the computer could function with either the Ethernet interface board or the USB interface board. 
Additionally the interface could function as the radio was directly wired to the computer with a standard 
Ethernet cable or run through a router or switch. 


With the advent of the Ethernet board M etis, and comtemplating the differences between the USB2 
protocol and the Ethernet protocol, several interesting features were included with the M etis board. 


First, the FPGA on the Penelope TX board and the Mercury RX board had the capability of being 
programmed with the] TAG protocol. Up to this point, we used the Altera software to connect to a 
JTAG connector or to the flash memory interface. We realized that the FPGA could be programmed to 
function asaJTAG programmer. This still required the setting of jumper pins but no additional 
hardware was necessary to program the FPGAs on the component boards. 


Also, to use the firmware] TAG programmer, the code was stored in a different part of the M etis Board 
from the regular communication code. This bootloader code in M etis need to be separate from the 
communication code. This brought us to the point where there was a need to develop custom software 
to use these firmware programming features. 
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B ootloader-Programmer 


The first effort at producing a custom programmer was by John, GOORX. Because of the dedicated 
USB cable between Ozymandis board and the computer, the board would pull the firmware from the 
computer at every power up. 


In the Ethernet context, the connection is a shared link and there needs to be software to filter the 
Ethernet packets for the radio. There can be other devices on the subnet, so both ends of the connection 
need to provide filtering. Also in tcpip protocols in the radio needs to understand ip addressing and 
packet types. This turned on to be a considerable programming task in the in Verilog in FPGA. There 
are commercial proprietary libraries for this but that interfered with the projects commitment to open 
source code. In the openH PSDR project, communications code was programmed from scratch to abide 
with the open source approach to our code base. 


There is a Ethernet protocol that requires less code that is a basic protocol. It is the “pcap” protocol, 
which uses MAC addressing instead of IP addressing. This is the same protocol used in the Wireshark 
program and because of the opportunity for this protocol to impact the code at each end of the 
connection the client computer must be run as administrator or root account. 


Additionally because the job of the B ootloader-Programmer is to erase or insert new code in the FPGA, 
itis possible to complete the code erase without the accompanying replacement. A simple bit of 
firmware was created that speaks to the B ootloader-Programmer in “pcap” protocol. Bootloader 
firmware is loaded at manufacturing and testing on the board and should never need to be replaced. 
This provides a way for one to recover from hardware or operator errors that erase firmware. Itis 
possible to erase the bootloader firmware but not with the openHPSDR programs. Only by using the 
original Altera software. 


The original code would allow the user to replace the M etis board firmware or by using the bootloader 
firmware as a] TAG programmer to program the firmware in other component Atlas bus boards. This 
code is fully functional and can replace all firmware that a normal user should need to replace. This 
programmer is coded in C++ programming language using the QT graphics library for the GU| 
(Graphical User Interface). The big disadvantages is that it used “pcap” Ethernet protocol requiring the 
B ootloader-Programmer to be run as administrator or root user. It also requires the bootloader jumper to 
be set on the board to run the bootloader firmware. Thirdly the programmer worked differently if 
programming the connected board or using the connected board as a] TAG to program a secondary 
board (See Figure 1). Also we discovered a quirk that the board to be programmed with J TAG worked 
best if the M etis board was in Atlas slot furthest from the power supply and the board to be programmed 
with JTAG protocol in the slot next to the M etis board. This was due to a quirk in how the Atlas bus 
was wired in the PCB long before this procedure was imagined. 
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Metis ethernet 


Jumper 1 


Hermes 
Jumper 12 


Angelia 


Jumper 17 


Figure 1 is a diagram of how the HPSDR Bootloader access the component boards of the HPSDR 
system. 


We also found that some occasional users found the workflow confusing mainly because they did not 
clearly understand the information described above. This lead to the point where | started working on 
the firmware programming code. John GOORX is avery energetic programmer and had moved on to 
other problems, as the Bootloader-Programmer was stable from his point of view. At work, | had been 
using C++ and Qt for the previous 10 years, so | volunteered to take on this task. 


Spliting the GOORX code 


The first idea was to split the B ootloader-Programmer into two programs both to work more or less like 
the original but with a cleaner GUI from a user perspective. This program would keep using the pcap 
library and the requirements to run as administrator or root user, set the bootloader jumper. It provided 
information on if the expected board is found and if itis programmed successfully. This program was 
labeled the HPSDR Bootloader program is intended to recover from situations with firmware corruption 
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issues. A second program was defined that only programmed Ethernet connected boards and the was 
called the HPSDR Programmer(See Figure 3). 


| HPSDRBootloader (version 2.0.4.4) 2015-1-29 —- + XxX 
File Tools Help 
OP) er: 
Computer Interface 
Interface: |enp0s20 ¥ 
Computer IP Address: 192.168.1.10 Computer MAC: 00:1F:C6:7E:52:DE 
Board Bootloader 
Board MAC address: 00:04:A3:64:25:95 Board with Bootloader Found Test for Bootloader | 
Board Programmer 
/home/dlarsen/Downloads/Hermes_v3.2.rbf 1 Browse 
Program 
Use Board as a JTAG Programmer 
interrogate 
Firmware RBF file Browse Program 
Reading rbf file: /home/dlarsen/Downloads/Hermes_v3.2.rbf oe 


Figure 2. is a diagram of the HPSDR Bootloader program after Board discovery and prepared to program 
the Hermes board. 


H PSDR Programmer 


The first HPSDR Programmer was designed to only change the firmware in the connected board. This 
version still used pcap but only communicated to the boards directly connect to the client computer. 
This was intended to be an interim version as | was reorganizing the code. 


HPSDRProgrammer_V2 


During this time, the Hermes board was released. M ost users of the single board radios want to put 
them in a box and this made accessing jumper pins much less convenient. Also, all the functions were 
fit into a single larger FPGA, eliminating the need for a software] TAG programmer. The 
HPSDRProgrammer_V 2 used a different Ethernet protocol UDP to communicate with the radio board. 
This is the same Ethernet Protocol used by the radio communication software, so it was already in the 
firmware of the FPGA. It did not need to be run as administrator or root user, it did not have to change 
bootloader jumper and it did not use the pcap library. The HPSDRProgrammer_V 2 depends that the 
current version of the firmware has the code to talk to the HPSDRProgrammer_V 2, which works well 
until there is a programmer failure or the user loads very old firmware. This software became popular 
with the advent of the single board radios starting with the Hermes board (See Figure 3). 


HPSDRProgrammer V2 nopcap (version 2.0.4.10) 2014-7-2 - 


File Tools Help 


ae ee 
Interface 

Computer interface | enp0s20 aA 

Computer IP address: 192.168.1.10 MAC; 00:1F:C6:7E:52:DE 

Device 

00:04:A3:D3:b1:59 (192.168.1.59) Software version: 3.0 (metis) | 7 Discover 
Programmer 

RBF file 

| /home/dlarsen/Downloads/Metis_v3.0.rbf || Browse 

| Program 
S) 


Figure 3. is an example of the HPSDR Programmer_V 2 program with the metis board discovered and 


ready to load the firmware into the board. 


A new way of implementing HPSDR radio protocol 


Over the years, there have been several nagging issues that seem to be corner cases for the majority of 
users but they are very important to the individuals that report these cases. M ost of these were hard or 
impossible to fix due the lack of information on what was actually happening with the transferred 
packets. The previous software was not helpful as producing feedback. So most user could not provide 
and information that was useful in debugging their problems. 


This situation brought about the need to upgrade the protocol starting in 2015, this new protocol is now 
labeled protocol2 in the code repository. The first protocol, labeled protocoll, was a simple statement of 
the information being sent back and forth and was in part based on the older USB protocol. Since the 
starting point on the computer client software was aversion of PowerSDR shared by FlexRadio 10 years 
ago over the years the software used by openHPSDR and FlexRadio have diverged. 


In protocol2, the protocol has been vetted over a number of years by many people writing computer 
client software. It attempts to better use the bandwidth in a way the client program can use. And 
provide debugging information of the current status of the communication process. 


As for my own interest, | had taken a 2-year break from working on the HPSDRProgrammer as the code 
was stable. As you can imagine with the sequence of revisions programmer code accumulates unused 
bits of code that are either bypassed or saved as they might be useful later. | wanted to write a clean 
new set of code that | fully understand as | would write it all myself. Writing this code is not my job, it 
is my hobby, so | want to have a clear idea of the process in my coding style. As the protocol2 was 
evolving at the time, | decided to start with the protocoll. Also since! am Linux programmer, | thought 
| would start with a command line program for simplicity and building the complete programmer with 
the least amount of code. It is important to know that about 30% of the older code is necessary to 
program the radio board the other 70% of the code is to communication the the program user. 


HPSDR Programmer in a new language 


Also at the time, | had learned a new programming language at work, so | thought | would apply it to 
this problem. With the C++ code, | was frustrated with my ability to test the bits of code out of context 
of the program. The new language! decided to use is Go (often referred to as golang) (golang.org). Go 
iS a open source language started at Google in 2007 since 2012 is has stable and quite usable. Go hada 
good linage for a starting place. K en Thompson (Plan9 OS, The B programming language a predecessor 
of the C programming language) and Rob Pike (worked on the practice of “Programming and the Unix 
operating system manual”, and Plan9 with Ken Thompson) both work for many years a Bell Labs and 
both developed UTF-8 and were latter hired to work at Google. Robert Griesemer the third co-creator 
that worked on database structures. After producing a stable Linux implementation they open-sourced 
the code and since then over half of the code developments have come from a dedicated open-source 
community. 


Go, while a robust language in most ways has no GUI in the normal sense. It does have a very robust 
networking package include normal tcpip, pcap, and support for making web servers. It also has a 
robust testing environment. So that you can be comfortable that each subcomponent is working correctly 
and as new releases of the language come along you can easily retest your code. 
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| first wrote a set of functions to perform all the basic steps in the programming process. W ith these 
functions, | built tests for each. Also, | added a debug mode that can be turned on by the user, that 
allows the code to report all bytes sent to the radio and all bytes returned. Additionally, these bytes can 
be displayed as decimal or hex numbers. This feature was quite helpful as it allow me to find an obscure 
error the new code. 


Go also can be compile on most of the common operating systems and some not so common operating 
systems. See the golang.org download web site for a list of available operating systems. Additionally 
the executable code produced by the compilers is statically linked so the program is a single executable 
file and reducing the need for program installers. Each operating system has a different approach to 
dealing with program installers and this make producing and distributing cross platform code much 
easier. Also the compiler system is moving to make the cross platform compiler much more robust. 


The disadvantage Is that since the advent of computer GUIs, people have become less familiar with 
command line programs especially on windows. 


All this being said | moved forward with a set of protocol1 functions to detect, erase, program and set 
the IP address on openHPSDR radios. The program was very fast and gave feedback of the status of the 
process (see Figure 4, for a screen capture of the program output). 


dlarsen@dave-Radio ~/drl/src/gocode/src/oak.snr.missouri.edu/daveradio/radio - + x 


File Edit View Search Terminal Help 


dlarsen@dave-Radio ~/drl/src/gocode/src/oak.snr.missouri.edu/daveradio/radio $ ./CmdHPSDRProgrammer -interface=enp0s20 
Computer: (00:1f:c6:7e:52:de) 
OS: linux (amd64) 4 CPU(s) 
IPV4: 192.168.1.10 
Mask: [255 255 255 6] 
Network: 192.168.1.0 


HPSDR Board: (0:4:a3:d3:b1:59) 
IPV4: 192.168.1.59 
Port: 1024 
Type: Metis 
Firmware: 3.0 
Status: not running 


PC : 192.168.1.10:1024 


dlarsen@dave-Radio ~/drl/src/gocode/src/oak.snr.missouri.edu/daveradio/radio $ fj 


Figures 4. is the output of the Protocol 1 command line programmer after discovery of a M etis board. 
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Once! completed the protocol1, | started the protocol2 Programmer as the protocols have several 
differences from the protocol1 code was working, | developed the new code as separate program. When 
| was working on the early version of the code the firmware was very rudimentary. | wrote the code to 
the protocol specifications using the testing functions so | was reasonably sure the code was working 
correctly. Then after the firmware was available it was very easy to get the last details working 
correctly (See Figure 5). 


dlarsen@dave-Radio ~/drl/src/gocode/src/oak.snr.missouri.edu/daveradio/newradio - + x 
File Edit View Search Terminal Help 
dlarsen@dave-Radio ~/drl/src/gocode/src/oak.snr.missouri.edu/daveradio/newradio $ ./HPSDRProgrammer_cmd -index=3 


2017/08/05 18:13:42 Computer: (00:1f:c6:7e:52:de) 

2017/08/05 18:13:42 OS: Linux (amd64) 4 CPU(s) 

2017/08/05 18:13:42 Username: Dave Larsen (dlarsen) /home/dlarsen 
2017/08/05 18:13:42 IPV4: 192.168.1.10 

2017/08/05 18:13:42 IPV6: fe80: :6448:da02:1cb:973d 

2017/08/05 18:13:42 Discover: 192.168.1.10:0 -> 255.255.255.255:1024 
2017/08/05 18:13:42 Received data: 60 bytes from 192.168.1.25:1024 


2017/08/05 18:13:42 0 
2017/08/05 18:13:42 


2017/08/05 18:13:42 Board Type: HERMES 

2017/08/05 18:13:42 HPSDR Board: (0:4:a3:64:25:95) 

2017/08/05 18:13:42 Board Address: 192.168.1.25:1024 

2017/08/05 18:13:42 Protocol: 2.9 

2017/08/05 18:13:42 Firmware: 10.0 

2017/08/05 18:13:42 Receivers: 2 

2017/08/05 18:13:42 Freq. Input: Phase word 

2017/08/05 18:13:42 IQ data format: Big-Endian IQ in 3 byte format 


2017/08/05 18:13:42 Status: not running 
dlarsen@dave-Radio ~/drl/src/gocode/src/oak.snr.missouri.edu/daveradio/newradio $ | 


Figures 5. is the output of the Protocol 2 command line programmer after discovery of a Hermes board. 


Now | had functions that completed the HPSDRProgramming task correctly for both protocols and | 
shared it with other project developers. It became clear, | needed and interface for a wider group of 
users. Go has built-in libraries that make building web servers almost trivial. Therefore, | decide to 
make the HPSDRProgrammer program with a web server interface. The user would start the program 
and control the tasks with a web browser. This became a good choice, as most everybody knows how to 
use a web browser. | also made the program with the web pages compiled into the single executable 
file so that it was the only file needed to perform the programming process (see Figure 6). 
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HPSDRProgrammer Web - Chromium - + x 
[) HPSDRProgrammer We x [a] 


€ CS | © localhost:8228/board/?board=0%3A4%3Aa3%3A64%3A25%3A95&index=3&boardtype=none Q 
== Apps [} HPSDRProgrammer [} kvlog [} Javascript impleme: 


HPSDR Programmer 


By Dave, KV@S - Version 0.2.8, Protocol >1.7 - Last Updated 2016-9-17 - openhpsdr.orc 


Computer 


Computer: (00:1f:c6:7e:52:de) 
OS: linux (amd64) 4 CPU(s) 
User: Dave Larsen (dlarsen) /home/dlarsen 
IPV4:192.168.1.10 
IPV6:fe80::6448:da02:1cb:973d 


Radios 


Please select from these available Radios 
HERMES: (0:4:a3:64:25:95) (192.168.1.25:1024) 


Selected Network interface:3: enp0s20 (00:1f:c6:7e:52:de) 


HERMES (0:4:a3:64:25:95) * 
Select HPSDR Board 
Board: HERMES 
Board Mac: 0:4:a3:64:25:95 
Board Address: 192.168.1.25:1024 
Board Status:not running 
Protocol: 2.9 
Firmware: 10.0 
Receivers:2 
Frequency Input: Phase_word 
IQ data format: Big-Endian IQ in 3 byte format 


Figure 6. is aDiagram of how the HPSDRProgrammer web interface after discovery of a Hermes board. 


One of the nice features of using a web browser, as the interface to a program is the web browser can 
also access help files or a manual on the programs operation. M ost of the issues that made the program 
difficult to implement relate to limits web browsers have on their ability to interact with the client 
computer. The limits are for the safety of the client computer when using the Internet but made it more 


difficult to access the radio firmware files and to let the user know the status of the programming 
process. 


Conclusion 


The development of the openH PSDR radios was a community process that focused on the development 
of very high quality radio systems. This allowed A mateur Radio operators the access to these 
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technologies in an open-source environment. The openHPSDR group is a collection of volunteers that 
do this work as their Amateur Radio hobby. 


M y development of the HPSDR Programmer programs is one small part of the project. M any projects 
can be developed in this project. Y ou do not have to be an expert in the whole system to contribute. It is 
very satisfying to be able to say that in some way | help create parts of this project. If you would like to 
be a part of the process, come and join us. 
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